7.4 Creating a display

Rendering a display in speedbar is completely flexible. When your button function is called, see Minor Display Modes, and Major Display Modes, you have control to insert anything you want.

The conventions allow almost anything to be inserted, but several helper functions are provided to make it easy to create the standardized buttons.

To understand the built in functions, each “button” in speedbar consists of four important pieces of data. The text to be displayed, token data to be associated with the text, a function to call, and some face to display it in.

When a function is provided, then that text becomes mouse activated, meaning the mouse will highlight the text.

Additionally, for data which can form deep trees, each line is given a depth which indicates how far down the tree it is. This information is stored in invisible text at the beginning of each line, and is used by the navigation commands.

Function: speedbar-insert-button text face mouse function &optional token prevline

This function inserts one button into the current location. text is the text to insert. face is the face in which it will be displayed. mouse is the face to display over the text when the mouse passes over it. function is called whenever the user clicks on the text.

The optional argument token is extra data to associated with the text. Lastly prevline should be non-nil if you want this line to appear directly after the last button which was created instead of on the next line.

Function: speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth

Create a tag line with exp-button-type for the small expansion button. This is the button that expands or contracts a node (if applicable), and exp-button-char the character in it (‘+’, ‘-’, ‘?’, etc.). exp-button-function is the function to call if it’s clicked on. Button types are bracket, angle, curly, expandtag, statictag, and nil. exp-button-data is extra data attached to the text forming the expansion button.

Next, tag-button is the text of the tag. tag-button-function is the function to call if clicked on, and tag-button-data is the data to attach to the text field (such a tag positioning, etc.). tag-button-face is a face used for this type of tag.

Lastly, depth shows the depth of expansion.

This function assumes that the cursor is in the speedbar window at the position to insert a new item, and that the new item will end with a CR.

Function: speedbar-insert-generic-list level list expand-fun find-fun

At level, (the current indentation level desired) insert a generic multi-level alist list. Associations with lists get ‘{+}’ tags (to expand into more nodes) and those with positions or other data just get a ‘>’ as the indicator. ‘{+}’ buttons will have the function expand-fun and the token is the cdr list. The token name will have the function find-fun and not token.

Each element of the list can have one of these forms:

(name . marker-or-number)

One tag at this level.

(name (name . marker-or-number) (name . marker-or-number) ... )

One group of tags.

(name marker-or-number (name . marker-or-number) ... )

One Group of tags where the group has a starting position.

When you use speedbar-insert-generic-list, there are some variables you can set buffer-locally to change the behavior. The most obvious is speedbar-tag-hierarchy-method. See Tag Hierarchy Methods.

Variable: speedbar-generic-list-group-expand-button-type

This is the button type used for groups of tags, whether expanded or added in via a hierarchy method. Two good values are curly and expandtag. Curly is the default button, and expandtag is useful if the groups also has a position.

Variable: speedbar-generic-list-tag-button-type

This is the button type used for a single tag. Two good values are nil and statictag. nil is the default, and statictag has the same width as expandtag.